<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <link rel="stylesheet" href="docgen-resources/docgen.css" type="text/css">
  <meta name="generator" content="FreeMarker Docgen (DocBook 5)">
  <title>
    FreeMarker Manual - ftl
  </title>
    <script type="text/javascript" src="docgen-resources/jquery.js"></script>
    <script type="text/javascript" src="docgen-resources/linktargetmarker.js"></script>
</head>
<body>

    <div class="navigation">
    <div class="breadcrumb">
<span class="breadcrumb">        You are here:
          <a href="index.html">Book</a>
            <b>></b>
          <a href="ref.html">Reference</a>
            <b>></b>
          <a href="ref_directives.html">Directive Reference</a>
            <b>></b>
          ftl
</span>    </div>
    <div class="bookmarks">
<span class="bookmarks">Bookmarks:
<a href="alphaidx.html">Alpha. index</a>, <a href="gloss.html">Glossary</a>, <a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a>, <a href="ref_builtins_alphaidx.html">?builtins</a>, <a href="ref_directive_alphaidx.html">#directives</a>, <a href="ref_specvar.html">.spec_vars</a>, <a href="app_faq.html">FAQ</a>, <a href="api/index.html">API</a>, <a href="../index.html">Home</a></span>    </div>
    <div class="pagers">
      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
<div class="pagerButton"><a href="ref_directive_t.html"><span class="hideA">Next page: </span>t, lt, rt</a></div><div class="pagerButton"><a href="ref_directive_stop.html">Previous page</a></div><div class="pagerButton"><a href="ref_directives.html">Parent page</a></div><div class="pagerButton"><a href="index.html">Contents</a></div>      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
    </div>
    </div>

<div id="mainContent">

  
  
  
  
  <h1 class="rank_section1"
        id="pageTopTitle">
<a name="ref_directive_ftl"></a>ftl  </h1>
    
    <div class="toc">
      <p>
        <b>
            Page Contents
        </b>
      </p>
      
  <ul class="noMargin">
      <li>
        <a href="#autoid_115">Synopsis</a>
      </li>
      <li>
        <a href="#autoid_116">Description</a>
      </li>
  </ul>
    </div>
    <a name="docgen_afterTheTOC"></a>
    
<a name="ref.directive.ftl"></a>
            
  
  
  
  <h2 class="rank_section2"
        >
<a name="autoid_115"></a>Synopsis  </h2>


          <pre class="metaTemplate">
<tt style="color: #A03D10">&lt;#ftl <i style="color: #DD4400">param1</i>=<i style="color: #DD4400">value1</i> <i style="color: #DD4400">param2</i>=<i style="color: #DD4400">value2</i> <i style="color: #DD4400">...</i> <i style="color: #DD4400">paramN</i>=<i style="color: #DD4400">valueN</i>&gt;</tt>
</pre>


          <p>Where:</p>

              <div class="itemizedlist">
<ul>
            <li>
              <tt style="color: #A03D10"><i style="color: #DD4400">param1</i></tt>,
              <tt style="color: #A03D10"><i style="color: #DD4400">param2</i></tt>, ...etc.:
              Name of the parameter. Not an expression. Allowed parameters
              are: <tt style="color: #A03D10">encoding</tt>,
              <tt style="color: #A03D10">strip_whitespace</tt>,
              <tt style="color: #A03D10">strip_text</tt>, ...etc. See below.
            </li>

            <li>
              <tt style="color: #A03D10"><i style="color: #DD4400">value1</i></tt>,
              <tt style="color: #A03D10"><i style="color: #DD4400">value2</i></tt>, ...etc.:
              The value of parameter. This must be a constant expression (as
              <tt style="color: #A03D10">true</tt>, or <tt style="color: #A03D10">&quot;ISO-8859-5&quot;</tt>, or
              <tt style="color: #A03D10">{x:1, y:2}</tt>). It can't use variables.
            </li>
          </ul>    </div>

        
            
  
  
  
  <h2 class="rank_section2"
        >
<a name="autoid_116"></a>Description  </h2>


          <p>Tells information about the template for FreeMarker and for
          other tools, also helps programs to automatically detect if a text
          file is an FTL file. This directive, if present, must be the very
          first thing in the template. Any <a href="gloss.html#gloss.whiteSpace">white-space</a> before this directive
          will be ignored. The old-syntax (<tt style="color: #A03D10">#</tt>-less) format
          of this directive is not supported.</p>

          <p>The settings (encoding, white-space stripping, etc.) given
          here has the highest precedence, that is, they will be used for the
          template regardless of any FreeMarker configuration settings.</p>

          <p>Parameters:</p>

              <div class="itemizedlist">
<ul>
            <li>
              <p><tt style="color: #A03D10">encoding</tt>: With this you can specify the
              encoding (charset) of the template in the template file itself.
              <span style="color:#333399; font-style:italic">(That is, this will be the
              <tt style="color: #A03D10">encoding</tt> setting of the newly created
              <tt style="color: #A03D10">Template</tt>, and not even the
              <tt style="color: #A03D10">encoding</tt> parameter to
              <tt style="color: #A03D10">Configuration.getTemplate</tt> can override
              it)</span>. Note however, that FreeMarker will try to find and
              interpret the <tt style="color: #A03D10">ftl</tt> directive first with the
              automatically guessed encoding (which depends on the FreeMarker
              configuration set by the programmers), and only then realizes if
              the <tt style="color: #A03D10">ftl</tt> directive dictates something
              different, and re-read the template with the new encoding. Thus,
              the template must be valid FTL until the end of
              <tt style="color: #A03D10">ftl</tt> tag with the encoding tried first. The
              valid values of this parameter are MIME-preferred charset names
              from the IANA Charset Registry, like ISO-8859-5, UTF-8 or
              Shift_JIS.</p>
            </li>

            <li>
              <p><tt style="color: #A03D10">strip_whitespace</tt>: This enables/disables
              <a href="dgui_misc_whitespace.html#dgui_misc_whitespace_stripping">white-space
              stripping</a>. Valid values are the boolean constants
              <tt style="color: #A03D10">true</tt> and <tt style="color: #A03D10">false</tt>. (And for
              backward compatibility, strings <tt style="color: #A03D10">&quot;yes&quot;</tt>,
              <tt style="color: #A03D10">&quot;no&quot;</tt>, <tt style="color: #A03D10">&quot;true&quot;</tt>,
              <tt style="color: #A03D10">&quot;false&quot;</tt>). The default value (i.e. when you
              don't use this parameter) depends on the FreeMarker
              configuration set by the programmers, but it should be
              <tt style="color: #A03D10">true</tt> for new projects.</p>
            </li>

            <li>
              <p><tt style="color: #A03D10">strip_text</tt>: When enabled, all top-level
              text in a template is removed when the template is parsed. This
              does not affect text within macros, directives, or
              interpolations. Valid values are the boolean constants
              <tt style="color: #A03D10">true</tt> and <tt style="color: #A03D10">false</tt>. (And for
              backward compatibility, strings <tt style="color: #A03D10">&quot;yes&quot;</tt>,
              <tt style="color: #A03D10">&quot;no&quot;</tt>, <tt style="color: #A03D10">&quot;true&quot;</tt>,
              <tt style="color: #A03D10">&quot;false&quot;</tt>). The default value (i.e. when you
              don't use this parameter) is <tt style="color: #A03D10">false</tt>.</p>
            </li>

            <li>
              <p><tt style="color: #A03D10">strict_syntax</tt>: This turns on/off
              ``strict syntax''. Valid values are the boolean constants
              <tt style="color: #A03D10">true</tt> and <tt style="color: #A03D10">false</tt>. (And for
              backward compatibility, strings <tt style="color: #A03D10">&quot;yes&quot;</tt>,
              <tt style="color: #A03D10">&quot;no&quot;</tt>, <tt style="color: #A03D10">&quot;true&quot;</tt>,
              <tt style="color: #A03D10">&quot;false&quot;</tt>). The default value (i.e. when you
              don't use this parameter) depends on the FreeMarker
              configuration set by the programmers, but it should be
              <tt style="color: #A03D10">true</tt> for new projects. <span style="color:#333399; font-style:italic">(Programmers: you must set explicitly this
              setting to <tt style="color: #A03D10">true</tt> for this:
              <tt style="color: #A03D10">config.setStrictSyntaxMode(true);</tt>)</span>
              For more information read: <a href="ref_depr_oldsyntax.html">Deprecated FTL constructs/Old FTL syntax</a></p>
            </li>

            <li>
              <p><tt style="color: #A03D10">ns_prefixes</tt>: This is a hash that
              associates prefixes with node namespaces. For example:
              <tt style="color: #A03D10">{&quot;e&quot;:&quot;http://example.com/ebook&quot;,
              &quot;vg&quot;:&quot;http://example.com/vektorGraphics&quot;}</tt>. This is
              mostly used with XML processing where the prefixes can be used
              in XML queries, but it also influences the working of <a href="ref_directive_visit.html">directives
              <tt>visit</tt> and <tt>recurse</tt></a>.
              Only one prefix can be registered for the same node namespace
              (otherwise an error will occur), so there is one-to-one relation
              between prefixes and node namespaces. Prefixes
              <tt style="color: #A03D10">D</tt> and <tt style="color: #A03D10">N</tt> are reserved. If
              you register prefix <tt style="color: #A03D10">D</tt>, then other than you
              associate the node namespace with prefix <tt style="color: #A03D10">D</tt>,
              you also set the default node namespace. Prefix
              <tt style="color: #A03D10">N</tt> can't be registered; it is used to denote
              nodes with no node namespace in certain places, when (and only
              when) prefix <tt style="color: #A03D10">D</tt> is registered. (To see the
              usage of default node namespace, <tt style="color: #A03D10">N</tt>, and
              prefixes in general, see the part about <a href="xgui.html">XML
              processing</a> and <a href="ref_directive_visit.html"><tt>visit</tt> and
              <tt>recurse</tt></a> in the reference.) The effect
              of <tt style="color: #A03D10">ns_prefixes</tt> is limited to a single <a href="dgui_misc_namespace.html">FTL namespace</a>, namely, to
              the FTL namespace that was created for the template. This also
              means that <tt style="color: #A03D10">ns_prefixes</tt> has effect only when
              an FTL namespace is created for the template that contains it,
              otherwise the <tt style="color: #A03D10">ns_prefixes</tt> parameter has no
              effect. An FTL namespace is made for a template when: (a) the
              template is the ``main'' template, that is, it is not invoked as
              a result of an <tt style="color: #A03D10">&lt;#include ...&gt;</tt>, but it
              is directly invoked (<span style="color:#333399; font-style:italic">with the
              <tt style="color: #A03D10">process</tt> Java method of class
              <tt style="color: #A03D10">Template</tt> or
              <tt style="color: #A03D10">Environment</tt></span>); (b) the template is
              invoked directly with <tt style="color: #A03D10">&lt;#import
              ...&gt;</tt>.</p>
            </li>

            <li>
              <p><tt style="color: #A03D10">attributes</tt>: This is a hash that
              associates arbitrary attributes (name-value pairs) to the
              template. The values of the attributes can be of any type
              (string, number, sequence... etc.). FreeMarker doesn't try to
              understand the meaning of the attributes. It's up to the
              application that encapsulates FreeMarker (as a Web application
              framework). Thus, the set of allowed attributes and their
              semantic is application (Web application framework) dependent.
              <span style="color:#333399; font-style:italic">Programmers: you can get the
              attributes associated with a <tt style="color: #A03D10">Template</tt> object
              with its <tt style="color: #A03D10">getCustomAttributeNames</tt> and
              <tt style="color: #A03D10">getCustomAttribute</tt> methods (inherited from
              <tt style="color: #A03D10">freemarker.core.Configurable</tt>). As the
              template attributes are associated with the
              <tt style="color: #A03D10">Template</tt> object when the template is parsed,
              the attributes can be read anytime, the template need not be
              executed. The methods mentioned return the attribute values
              unwrapped, that is, with FreeMarker independent type as
              <tt style="color: #A03D10">java.util.List</tt>.</span></p>
            </li>
          </ul>    </div>


          <p>This directive also determines if the template uses angle
          bracket syntax (e.g. <tt style="color: #A03D10">&lt;#include 'foo.ftl'&gt;</tt>)
          or <a href="dgui_misc_alternativesyntax.html">square bracket
          syntax</a> (e.g. <tt style="color: #A03D10">[#include 'foo.ftl']</tt>).
          Simply, the syntax used for this directive will be the syntax used
          for the whole template, regardless of the FreeMarker configuration
          settings.</p>
          
</div>

    <div class="navigation">
    <div class="pagers">
      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
<div class="pagerButton"><a href="ref_directive_t.html"><span class="hideA">Next page: </span>t, lt, rt</a></div><div class="pagerButton"><a href="ref_directive_stop.html">Previous page</a></div><div class="pagerButton"><a href="ref_directives.html">Parent page</a></div><div class="pagerButton"><a href="index.html">Contents</a></div>      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
    </div>
    <div class="breadcrumb">
<span class="breadcrumb">        You are here:
          <a href="index.html">Book</a>
            <b>></b>
          <a href="ref.html">Reference</a>
            <b>></b>
          <a href="ref_directives.html">Directive Reference</a>
            <b>></b>
          ftl
</span>    </div>
    </div>

<table border=0 cellspacing=0 cellpadding=0 width="100%">
    <tr>
      <td colspan=2><img src="docgen-resources/img/none.gif" width=1 height=8 alt=""></td>
    <tr>
      <td align="left" valign="top"><span class="smallFooter">
            FreeMarker Manual -- For FreeMarker 2.3.20
            <br>
          HTML generated: 2013-06-27 20:54:33 GMT
      </span></td>
      <td align="right" valign="top"><span class="smallFooter">
          <a href="http://www.xmlmind.com/xmleditor/">
            <img src="docgen-resources/img/xxe.gif" alt="Edited with XMLMind XML Editor">
          </a>
      </span></td>
    </tr>
</table>
  <!-- Put pre-loaded images here: -->
  <div style="display: none">
    <img src="docgen-resources/img/linktargetmarker.gif" alt="Here!" />
  </div>
</body>
</html>

